February 1996

Using Graphics with Forms 4.5 Applications

By Daniel Bill

Wouldn't it be great to incorporate charts right into your Forms Designer applications? Using charts from the Graphics Designer and the OG.PLL library of functions and procedures of Forms, you can create useful and stunning presentations. Pie charts, bar charts, and line charts provide a great way of visualizing numeric data and comparing values. Imagine the benefit of using a pie chart to compare total expenses by category, or using a bar chart to show the number of orders by item.

Figure A shows a graphics display embedded in a form to create a master/detail situation, where the master block shows department information and the detail block graphically shows salaries and commissions for all employees in the department. We'll use this example to step through the process of integrating a Graphics chart into a Forms application. Our primary focus will be to show you the tools and techniques for embedding graphics into forms. However, we can't cover all the tools in one article, so look for this topic to be continued in future issues. Before we dive in, let's look at how embedding works.

Basic concepts

To start off, you must define everything relating to the chart in Graphics Designer, including the type of chart, the colors used, the query defining the chart content, etc. Figure B contains a diagram of the major components of a graphics file and shows their relationship to forms. The main components of a graphics file that we're concerned with are charts, queries, parameters, and program units. The chart can display quantitative data in several ways, i.e., pie charts, bar charts, and line charts. We use SQL queries to define the data represented in the chart. Parameters are, in effect, global variables that can be used in Graphics to modify the query. When you create parameters, you give them a name, a data type, and an initial value. Parameters are very important here because we use them to pass information from Forms to Graphics, enabling the master/detail relationship to work. A graphics file may also contain program units-PL/SQL functions and procedures. We use program units to modify the behavior of the Graphics application. With these components in mind, let's see how to embed a Graphics item into Forms and how the two communicate.

Your Forms application embeds a graphics display through a chart item placed on one of your form's canvases. You can think of the chart item as a window to your graphics display. The toolbar of the Layout Editor contains an icon representing the chart item (). All communication between the form and the graphics file occurs through the OG (Oracle Graphics) package-a library of PL/SQL program units. Figure C describes each of these functions and procedures. We'll consider only the OG.OPEN and the OG.INTERPRET procedures in this article. We'll use the OG.OPEN procedure to link the chart in our graphics file with the chart item in our form. We'll then use the OG.INTERPRET function to change the criteria of our chart by passing it a new parameter value and to run a program unit to update the chart for us. In our example, we're linking two separate tools to create one integrated application.

FIGURE C

OG.OPEN Opens the Graphics display in the chart item of the form

OG.CLOSE Closes the Graphics display

OG.GETNUMPARAM Gets the value of a specific numeric parameter from Graphics

OG.GETCHARPARAM Gets the value of a specific character parameter from a Graphics object

OG.INTERPRET Executes a Graphics program unit or specified PL/SQL code; also changes parameter values

OG.MOUSEUP Sends a mouse up event to Graphics

OG.MOUSEDOWN Sends a mouse down event to Graphics

OG.REFRESH Updates the Graphics chart displayed in the chart item

The OG library contains these functions and procedures.

Creating the Graphics chart

With these fundamentals in mind, let's go through the process of creating the application shown in Figure A. We'll start by creating the graphics chart using Oracle Graphics. Then we'll create the form that uses the chart, including all the links needed to create the master detail relationship. We'll use two of Oracle's demo tables, Dept and Emp, in our example.

To create the chart, start up Graphics Designer, and then from the Layout Editor select the chart icon. Select the top-left corner of the chart and then drag the mouse diagonally to select the second corner. You'll now automatically switch to the Chart Genie screen, where you can enter the query that defines the chart's content.

Fill out the Chart Genie as shown in Figure D and click OK. Notice the last line of the SQL statement

where deptno = :department;

Here we're referencing a parameter called :department. Since this parameter does not yet exist, you'll be prompted to create it, as shown in Figure E. Click Yes to automatically create the parameter. When the Parameters dialog box appears, enter the Name, Type, and Initial Value as shown in Figure F. Remember, parameters are the key for passing information between Forms and Graphics.

When the Chart Properties screen appears, name the chart and give it a title and select the chart type and subtype, as shown in Figure G . Then select the Data tab, enter the query name, and make sure that the Update chart on query execution field is checked. This will ensure that the Graphics object updates the chart when Forms passes the new query parameter.

Next, we need to indicate which field from our query we want to be the Category and which field we want to be the Value. Now click the Categories tab. The Chart category should show ENAME (the employee's name) as the label for each bar in the chart. The Values tab should show SAL and COMM as the chart values. Your chart is now complete.

Creating the Graphics procedure

Later we'll see that Forms instructs Graphics to update the chart based on a new parameter value using the OG.INTERPRET function. One of the arguments we'll pass in the function OG.INTERPRET is the name of a Graphics procedure used to update the chart. Let's create that Graphics procedure now. Select the Program Unit heading from the Object Navigator and then click the Create button. Name the procedure do_update and enter the code as shown in Figure H. This procedure simply executes the salary query created earlier. Compile the Graphics document you created and then save it as emp_sal.ogd.

Creating the form

Now let's create the form that will reference our Graphics chart. Open a new form and create a block based on the Dept table. Connect to your database containing the Oracle demo tables. Select the New Block option on the Tools menu, and type Dept in the Base table field. Click OK to create the block.

Create a second block on the form to contain the chart item. This time, name the block Chart and leave the Base table field blank. It's important that this block appear as the second block on the form and not the first. Now, using the Layout Editor, create a chart item in your Chart block by selecting the chart icon and, using your mouse, drag the chart to size on the canvas. Name the chart item salchart. Now with all the form objects in place, let's move on to creating the triggers that will communicate with Graphics.

Using OG program units to communicate with Graphics

Earlier, we mentioned the OG.PLL library and the program units it contains. These are the tools that allow us to communicate with Graphics from Forms. All we need to do now is create two triggers that use OG program units-one to link the chart item in our form with the Graphics file and the other to change the chart based on the value of the Dept block.

Attaching the library

Before we can use the OG library procedures, we must attach the library to the form. In the Object Navigator, highlight the Library heading within the form, and then click the Create button. In the Attach Library dialog box, click the Find button to find the og.pll file, as shown in Figure I. Click OK to complete the attachment.

Creating the triggers

The first trigger we need is a WHEN-NEW-FORM-INSTANCE trigger, which fires when you load the form and will open your Graphics chart in the chart item in the form. Select the Triggers heading in the Object Navigator (located just below the form name) and then click the Create button. Enter the code for the trigger, as shown in Figure J. The first argument in the OG.OPEN procedure is the name of the Graphics file to be linked. The second argument is the name of the chart item you created in the form, preceded by the block name. The third argument is a Boolean parameter (TRUE or FALSE). When the argument is set to TRUE, Graphics will use the default chart size, cropping the display as needed; when it's set to FALSE, Graphics will scale the chart display to fit the chart item size.

Now we need a trigger that will pass a parameter from Forms to Graphics and tell Graphics to re-query the chart based on a new parameter value. We'll use a WHEN-NEW-RECORD-INSTANCE trigger on the Dept block. Enter the code for the trigger as shown in Figure K.

The main component of this trigger is the OG.INTERPRET procedure. This procedure transfers the department ID (the deptno field) from Forms to Graphics and tells Graphics to update the chart based on this value. The first argument is the name of the graphics file, and the second is the name of the chart item in the form. The third argument tells Graphics to run the do_update procedure (don't forget to include the semi-colon (;) at the end). The fourth argument indicates whether the chart item in your form should be refreshed after running the procedure in Graphics. The final argument is the name of the parameter list containing the deptno value. All the other code in this trigger deals with creating the parameter list, adding a value to it, and finally, destroying the parameter list. Note the arguments in the procedure ADD_PARAMETER: first, the name of the parameter list; second, the name of the parameter we created in Graphics; third, the type of parameter; and finally, the value of the parameter. The ADD_PARAMETER procedure requires a character type for the parameter value.

Running the form

Now run your form by choosing Run from the File menu, and Forms will fire the WHEN-NEW-FORM-INSTANCE trigger that will display your Graphics chart in the second block of your form. If you query the departments in the Dept block, the WHEN-NEW-RECORD-INSTANCE trigger will fire, and the chart will be updated to show you the salaries of the employees in that department. Scroll through the departments and watch the chart information change.

Conclusion

Integrating Graphics into Forms can add a whole new dimension to your Forms application. We've covered just one example of what a link between these two products can do. Watch for more coverage of this topic in future issues.

[Return to Index for Exploring Oracle Developer/2000 and Designer/2000 - February 1996]

Reproduction in whole or in part in any form or medium without express written permission of Ziff-Davis

Publishing Company is prohibited. The Cobb Group and The Cobb Group logo are trademarks of

Ziff-Davis Publishing Company.